home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / popt.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-02-15  |  15.6 KB  |  542 lines
  1. /** \file popt/popt.h
  2.  * \ingroup popt
  3.  */
  4.  
  5. /* (C) 1998-2000 Red Hat, Inc. -- Licensing details are in the COPYING
  6.    file accompanying popt source distributions, available from 
  7.    ftp://ftp.rpm.org/pub/rpm/dist. */
  8.  
  9. #ifndef H_POPT
  10. #define H_POPT
  11.  
  12. #include <stdio.h>            /* for FILE * */
  13.  
  14. #define POPT_OPTION_DEPTH    10
  15.  
  16. /** \ingroup popt
  17.  * \name Arg type identifiers
  18.  */
  19. /*@{*/
  20. #define POPT_ARG_NONE        0    /*!< no arg */
  21. #define POPT_ARG_STRING        1    /*!< arg will be saved as string */
  22. #define POPT_ARG_INT        2    /*!< arg will be converted to int */
  23. #define POPT_ARG_LONG        3    /*!< arg will be converted to long */
  24. #define POPT_ARG_INCLUDE_TABLE    4    /*!< arg points to table */
  25. #define POPT_ARG_CALLBACK    5    /*!< table-wide callback... must be
  26.                        set first in table; arg points 
  27.                        to callback, descrip points to 
  28.                        callback data to pass */
  29. #define POPT_ARG_INTL_DOMAIN    6       /*!< set the translation domain
  30.                        for this table and any
  31.                        included tables; arg points
  32.                        to the domain string */
  33. #define POPT_ARG_VAL        7    /*!< arg should take value val */
  34. #define    POPT_ARG_FLOAT        8    /*!< arg will be converted to float */
  35. #define    POPT_ARG_DOUBLE        9    /*!< arg will be converted to double */
  36.  
  37. #define POPT_ARG_MASK        0x0000FFFF
  38. /*@}*/
  39.  
  40. /** \ingroup popt
  41.  * \name Arg modifiers
  42.  */
  43. /*@{*/
  44. #define POPT_ARGFLAG_ONEDASH    0x80000000  /*!< allow -longoption */
  45. #define POPT_ARGFLAG_DOC_HIDDEN 0x40000000  /*!< don't show in help/usage */
  46. #define POPT_ARGFLAG_STRIP    0x20000000  /*!< strip this arg from argv(only applies to long args) */
  47. #define    POPT_ARGFLAG_OPTIONAL    0x10000000  /*!< arg may be missing */
  48.  
  49. #define    POPT_ARGFLAG_OR        0x08000000  /*!< arg will be or'ed */
  50. #define    POPT_ARGFLAG_NOR    0x09000000  /*!< arg will be nor'ed */
  51. #define    POPT_ARGFLAG_AND    0x04000000  /*!< arg will be and'ed */
  52. #define    POPT_ARGFLAG_NAND    0x05000000  /*!< arg will be nand'ed */
  53. #define    POPT_ARGFLAG_XOR    0x02000000  /*!< arg will be xor'ed */
  54. #define    POPT_ARGFLAG_NOT    0x01000000  /*!< arg will be negated */
  55. #define POPT_ARGFLAG_LOGICALOPS \
  56.         (POPT_ARGFLAG_OR|POPT_ARGFLAG_AND|POPT_ARGFLAG_XOR)
  57.  
  58. #define    POPT_BIT_SET    (POPT_ARG_VAL|POPT_ARGFLAG_OR)
  59.                     /*!< set arg bit(s) */
  60. #define    POPT_BIT_CLR    (POPT_ARG_VAL|POPT_ARGFLAG_NAND)
  61.                     /*!< clear arg bit(s) */
  62.  
  63. #define    POPT_ARGFLAG_SHOW_DEFAULT 0x00800000 /*!< show default value in --help */
  64.  
  65. /*@}*/
  66.  
  67. /** \ingroup popt
  68.  * \name Callback modifiers
  69.  */
  70. /*@{*/
  71. #define POPT_CBFLAG_PRE        0x80000000  /*!< call the callback before parse */
  72. #define POPT_CBFLAG_POST    0x40000000  /*!< call the callback after parse */
  73. #define POPT_CBFLAG_INC_DATA    0x20000000  /*!< use data from the include line,
  74.                            not the subtable */
  75. #define POPT_CBFLAG_SKIPOPTION    0x10000000  /*!< don't callback with option */
  76. #define POPT_CBFLAG_CONTINUE    0x08000000  /*!< continue callbacks with option */
  77. /*@}*/
  78.  
  79. /** \ingroup popt
  80.  * \name Error return values
  81.  */
  82. /*@{*/
  83. #define POPT_ERROR_NOARG    -10    /*!< missing argument */
  84. #define POPT_ERROR_BADOPT    -11    /*!< unknown option */
  85. #define POPT_ERROR_OPTSTOODEEP    -13    /*!< aliases nested too deeply */
  86. #define POPT_ERROR_BADQUOTE    -15    /*!< error in paramter quoting */
  87. #define POPT_ERROR_ERRNO    -16    /*!< errno set, use strerror(errno) */
  88. #define POPT_ERROR_BADNUMBER    -17    /*!< invalid numeric value */
  89. #define POPT_ERROR_OVERFLOW    -18    /*!< number too large or too small */
  90. #define    POPT_ERROR_BADOPERATION    -19    /*!< mutually exclusive logical operations requested */
  91. #define    POPT_ERROR_NULLARG    -20    /*!< opt->arg should not be NULL */
  92. #define    POPT_ERROR_MALLOC    -21    /*!< memory allocation failed */
  93. /*@}*/
  94.  
  95. /** \ingroup popt
  96.  * \name poptBadOption() flags
  97.  */
  98. /*@{*/
  99. #define POPT_BADOPTION_NOALIAS  (1 << 0)  /*!< don't go into an alias */
  100. /*@}*/
  101.  
  102. /** \ingroup popt
  103.  * \name poptGetContext() flags
  104.  */
  105. /*@{*/
  106. #define POPT_CONTEXT_NO_EXEC    (1 << 0)  /*!< ignore exec expansions */
  107. #define POPT_CONTEXT_KEEP_FIRST    (1 << 1)  /*!< pay attention to argv[0] */
  108. #define POPT_CONTEXT_POSIXMEHARDER (1 << 2) /*!< options can't follow args */
  109. #define POPT_CONTEXT_ARG_OPTS    (1 << 4) /*!< return args as options with value 0 */
  110. /*@}*/
  111.  
  112. /** \ingroup popt
  113.  */
  114. struct poptOption {
  115. /*@observer@*/ /*@null@*/ const char * longName; /*!< may be NULL */
  116.     char shortName;            /*!< may be '\0' */
  117.     int argInfo;
  118. /*@shared@*/ /*@null@*/ void * arg;    /*!< depends on argInfo */
  119.     int val;            /*!< 0 means don't return, just update flag */
  120. /*@observer@*/ /*@null@*/ const char * descrip;    /*!< description for autohelp -- may be NULL */
  121. /*@observer@*/ /*@null@*/ const char * argDescrip; /*!< argument description for autohelp */
  122. };
  123.  
  124. /** \ingroup popt
  125.  * A popt alias argument for poptAddAlias().
  126.  */
  127. struct poptAlias {
  128. /*@owned@*/ /*@null@*/ const char * longName;    /*!< may be NULL */
  129.     char shortName;        /*!< may be '\0' */
  130.     int argc;
  131. /*@owned@*/ const char ** argv;    /*!< must be free()able */
  132. };
  133.  
  134. /** \ingroup popt
  135.  * A popt alias or exec argument for poptAddItem().
  136.  */
  137. /*@-exporttype@*/
  138. typedef struct poptItem_s {
  139.     struct poptOption option;    /*!< alias/exec name(s) and description. */
  140.     int argc;            /*!< (alias) no. of args. */
  141. /*@owned@*/ const char ** argv;    /*!< (alias) args, must be free()able. */
  142. } * poptItem;
  143. /*@=exporttype@*/
  144.  
  145. /** \ingroup popt
  146.  * \name Auto-generated help/usage
  147.  */
  148. /*@{*/
  149.  
  150. /**
  151.  * Empty table marker to enable displaying popt alias/exec options.
  152.  */
  153. /*@-exportvar@*/
  154. /*@unchecked@*/ /*@observer@*/
  155. extern struct poptOption poptAliasOptions[];
  156. /*@=exportvar@*/
  157. #define POPT_AUTOALIAS { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptAliasOptions, \
  158.             0, "Options implemented via popt alias/exec:", NULL },
  159.  
  160. /**
  161.  * Auto help table options.
  162.  */
  163. /*@-exportvar@*/
  164. /*@unchecked@*/ /*@observer@*/
  165. extern struct poptOption poptHelpOptions[];
  166. /*@=exportvar@*/
  167. #define POPT_AUTOHELP { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptHelpOptions, \
  168.             0, "Help options:", NULL },
  169.  
  170. #define POPT_TABLEEND { NULL, '\0', 0, 0, 0, NULL, NULL }
  171. /*@}*/
  172.  
  173. /** \ingroup popt
  174.  */
  175. /*@-exporttype@*/
  176. typedef /*@abstract@*/ struct poptContext_s * poptContext;
  177. /*@=exporttype@*/
  178.  
  179. /** \ingroup popt
  180.  */
  181. #ifndef __cplusplus
  182. /*@-exporttype -typeuse@*/
  183. typedef struct poptOption * poptOption;
  184. /*@=exporttype =typeuse@*/
  185. #endif
  186.  
  187. /*@-exportconst@*/
  188. enum poptCallbackReason {
  189.     POPT_CALLBACK_REASON_PRE    = 0, 
  190.     POPT_CALLBACK_REASON_POST    = 1,
  191.     POPT_CALLBACK_REASON_OPTION = 2
  192. };
  193. /*@=exportconst@*/
  194.  
  195. #ifdef __cplusplus
  196. extern "C" {
  197. #endif
  198. /*@-type@*/
  199.  
  200. /** \ingroup popt
  201.  * Table callback prototype.
  202.  * @param con        context
  203.  * @param reason    reason for callback
  204.  * @param opt        option that triggered callback
  205.  * @param arg        @todo Document.
  206.  * @param data        @todo Document.
  207.  */
  208. typedef void (*poptCallbackType) (poptContext con, 
  209.         enum poptCallbackReason reason,
  210.         /*@null@*/ const struct poptOption * opt,
  211.         /*@null@*/ const char * arg,
  212.         /*@null@*/ const void * data)
  213.     /*@*/;
  214.  
  215. /** \ingroup popt
  216.  * Initialize popt context.
  217.  * @param name
  218.  * @param argc        no. of arguments
  219.  * @param argv        argument array
  220.  * @param options    address of popt option table
  221.  * @param flags        or'd POPT_CONTEXT_* bits
  222.  * @return        initialized popt context
  223.  */
  224. /*@only@*/ /*@null@*/ poptContext poptGetContext(
  225.         /*@dependent@*/ /*@keep@*/ const char * name,
  226.         int argc, /*@dependent@*/ /*@keep@*/ const char ** argv,
  227.         /*@dependent@*/ /*@keep@*/ const struct poptOption * options,
  228.         int flags)
  229.     /*@*/;
  230.  
  231. /** \ingroup popt
  232.  * Reinitialize popt context.
  233.  * @param con        context
  234.  */
  235. /*@-exportlocal@*/
  236. void poptResetContext(/*@null@*/poptContext con)
  237.     /*@modifies con @*/;
  238. /*@=exportlocal@*/
  239.  
  240. /** \ingroup popt
  241.  * Return value of next option found.
  242.  * @param con        context
  243.  * @return        next option val, -1 on last item, POPT_ERROR_* on error
  244.  */
  245. int poptGetNextOpt(/*@null@*/poptContext con)
  246.     /*@globals fileSystem, internalState @*/
  247.     /*@modifies con, fileSystem, internalState @*/;
  248.  
  249. /*@-redecl@*/
  250. /** \ingroup popt
  251.  * Return next option argument (if any).
  252.  * @param con        context
  253.  * @return        option argument, NULL if no more options are available
  254.  */
  255. /*@observer@*/ /*@null@*/ const char * poptGetOptArg(/*@null@*/poptContext con)
  256.     /*@modifies con @*/;
  257.  
  258. /** \ingroup popt
  259.  * Return current option's argument.
  260.  * @param con        context
  261.  * @return        option argument, NULL if no more options are available
  262.  */
  263. /*@observer@*/ /*@null@*/ const char * poptGetArg(/*@null@*/poptContext con)
  264.     /*@modifies con @*/;
  265.  
  266. /** \ingroup popt
  267.  * Peek at current option's argument.
  268.  * @param con        context
  269.  * @return        option argument
  270.  */
  271. /*@observer@*/ /*@null@*/ const char * poptPeekArg(/*@null@*/poptContext con)
  272.     /*@*/;
  273.  
  274. /** \ingroup popt
  275.  * Return remaining arguments.
  276.  * @param con        context
  277.  * @return        argument array, terminated with NULL
  278.  */
  279. /*@observer@*/ /*@null@*/ const char ** poptGetArgs(/*@null@*/poptContext con)
  280.     /*@modifies con @*/;
  281.  
  282. /** \ingroup popt
  283.  * Return the option which caused the most recent error.
  284.  * @param con        context
  285.  * @param flags
  286.  * @return        offending option
  287.  */
  288. /*@observer@*/ const char * poptBadOption(/*@null@*/poptContext con, int flags)
  289.     /*@*/;
  290. /*@=redecl@*/
  291.  
  292. /** \ingroup popt
  293.  * Destroy context.
  294.  * @param con        context
  295.  * @return        NULL always
  296.  */
  297. /*@null@*/ poptContext poptFreeContext( /*@only@*/ /*@null@*/ poptContext con)
  298.     /*@modifies con @*/;
  299.  
  300. /** \ingroup popt
  301.  * Add arguments to context.
  302.  * @param con        context
  303.  * @param argv        argument array, NULL terminated
  304.  * @return        0 on success, POPT_ERROR_OPTSTOODEEP on failure
  305.  */
  306. int poptStuffArgs(poptContext con, /*@keep@*/ const char ** argv)
  307.     /*@modifies con @*/;
  308.  
  309. /** \ingroup popt
  310.  * Add alias to context.
  311.  * @todo Pass alias by reference, not value.
  312.  * @deprecated Use poptAddItem instead.
  313.  * @param con        context
  314.  * @param alias        alias to add
  315.  * @param flags        (unused)
  316.  * @return        0 on success
  317.  */
  318. /*@unused@*/
  319. int poptAddAlias(poptContext con, struct poptAlias alias, int flags)
  320.     /*@modifies con @*/;
  321.  
  322. /** \ingroup popt
  323.  * Add alias/exec item to context.
  324.  * @param con        context
  325.  * @param newItem    alias/exec item to add
  326.  * @param flags        0 for alias, 1 for exec
  327.  * @return        0 on success
  328.  */
  329. int poptAddItem(poptContext con, poptItem newItem, int flags)
  330.     /*@modifies con @*/;
  331.  
  332. /** \ingroup popt
  333.  * Read configuration file.
  334.  * @param con        context
  335.  * @param fn        file name to read
  336.  * @return        0 on success, POPT_ERROR_ERRNO on failure
  337.  */
  338. int poptReadConfigFile(poptContext con, const char * fn)
  339.     /*@globals fileSystem, internalState @*/
  340.     /*@modifies con->execs, con->numExecs,
  341.         fileSystem, internalState @*/;
  342.  
  343. /** \ingroup popt
  344.  * Read default configuration from /etc/popt and $HOME/.popt.
  345.  * @param con        context
  346.  * @param useEnv    (unused)
  347.  * @return        0 on success, POPT_ERROR_ERRNO on failure
  348.  */
  349. int poptReadDefaultConfig(poptContext con, /*@unused@*/ int useEnv)
  350.     /*@globals fileSystem, internalState @*/
  351.     /*@modifies con->execs, con->numExecs,
  352.         fileSystem, internalState @*/;
  353.  
  354. /** \ingroup popt
  355.  * Duplicate an argument array.
  356.  * @note: The argument array is malloc'd as a single area, so only argv must
  357.  * be free'd.
  358.  *
  359.  * @param argc        no. of arguments
  360.  * @param argv        argument array
  361.  * @retval argcPtr    address of returned no. of arguments
  362.  * @retval argvPtr    address of returned argument array
  363.  * @return        0 on success, POPT_ERROR_NOARG on failure
  364.  */
  365. int poptDupArgv(int argc, /*@null@*/ const char **argv,
  366.         /*@null@*/ /*@out@*/ int * argcPtr,
  367.         /*@null@*/ /*@out@*/ const char *** argvPtr)
  368.     /*@modifies *argcPtr, *argvPtr @*/;
  369.  
  370. /** \ingroup popt
  371.  * Parse a string into an argument array.
  372.  * The parse allows ', ", and \ quoting, but ' is treated the same as " and
  373.  * both may include \ quotes.
  374.  * @note: The argument array is malloc'd as a single area, so only argv must
  375.  * be free'd.
  376.  *
  377.  * @param s        string to parse
  378.  * @retval argcPtr    address of returned no. of arguments
  379.  * @retval argvPtr    address of returned argument array
  380.  */
  381. int poptParseArgvString(const char * s,
  382.         /*@out@*/ int * argcPtr, /*@out@*/ const char *** argvPtr)
  383.     /*@modifies *argcPtr, *argvPtr @*/;
  384.  
  385. /** \ingroup popt
  386.  * Parses an input configuration file and returns an string that is a 
  387.  * command line.  For use with popt.  You must free the return value when done.
  388.  *
  389.  * Given the file:
  390. \verbatim
  391. # this line is ignored
  392.     #   this one too
  393. aaa
  394.   bbb
  395.     ccc   
  396. bla=bla
  397.  
  398. this_is   =   fdsafdas
  399.      bad_line=        
  400.   reall bad line  
  401.   reall bad line  = again
  402. 5555=   55555   
  403.   test = with lots of spaces
  404. \endverbatim
  405. *
  406. * The result is:
  407. \verbatim
  408. --aaa --bbb --ccc --bla="bla" --this_is="fdsafdas" --5555="55555" --test="with lots of spaces"
  409. \endverbatim
  410. *
  411. * Passing this to poptParseArgvString() yields an argv of:
  412. \verbatim
  413. '--aaa'
  414. '--bbb' 
  415. '--ccc' 
  416. '--bla=bla' 
  417. '--this_is=fdsafdas' 
  418. '--5555=55555' 
  419. '--test=with lots of spaces' 
  420. \endverbatim
  421.  *
  422.  * @bug NULL is returned if file line is too long.
  423.  * @bug Silently ignores invalid lines.
  424.  *
  425.  * @param fp        file handle to read
  426.  * @param *argstrp    return string of options (malloc'd)
  427.  * @param flags        unused
  428.  * @return        0 on success
  429.  * @see            poptParseArgvString
  430.  */
  431. /*@-fcnuse@*/
  432. int poptConfigFileToString(FILE *fp, /*@out@*/ char ** argstrp, int flags)
  433.     /*@globals fileSystem @*/
  434.     /*@modifies *fp, *argstrp, fileSystem @*/;
  435. /*@=fcnuse@*/
  436.  
  437. /** \ingroup popt
  438.  * Return formatted error string for popt failure.
  439.  * @param error        popt error
  440.  * @return        error string
  441.  */
  442. /*@-redecl@*/
  443. /*@observer@*/ const char *const poptStrerror(const int error)
  444.     /*@*/;
  445. /*@=redecl@*/
  446.  
  447. /** \ingroup popt
  448.  * Limit search for executables.
  449.  * @param con        context
  450.  * @param path        single path to search for executables
  451.  * @param allowAbsolute    absolute paths only?
  452.  */
  453. void poptSetExecPath(poptContext con, const char * path, int allowAbsolute)
  454.     /*@modifies con @*/;
  455.  
  456. /** \ingroup popt
  457.  * Print detailed description of options.
  458.  * @param con        context
  459.  * @param fp        ouput file handle
  460.  * @param flags        (unused)
  461.  */
  462. void poptPrintHelp(poptContext con, FILE * fp, /*@unused@*/ int flags)
  463.     /*@globals fileSystem @*/
  464.     /*@modifies *fp, fileSystem @*/;
  465.  
  466. /** \ingroup popt
  467.  * Print terse description of options.
  468.  * @param con        context
  469.  * @param fp        ouput file handle
  470.  * @param flags        (unused)
  471.  */
  472. void poptPrintUsage(poptContext con, FILE * fp, /*@unused@*/ int flags)
  473.     /*@globals fileSystem @*/
  474.     /*@modifies *fp, fileSystem @*/;
  475.  
  476. /** \ingroup popt
  477.  * Provide text to replace default "[OPTION...]" in help/usage output.
  478.  * @param con        context
  479.  * @param text        replacement text
  480.  */
  481. /*@-fcnuse@*/
  482. void poptSetOtherOptionHelp(poptContext con, const char * text)
  483.     /*@modifies con @*/;
  484. /*@=fcnuse@*/
  485.  
  486. /** \ingroup popt
  487.  * Return argv[0] from context.
  488.  * @param con        context
  489.  * @return        argv[0]
  490.  */
  491. /*@-redecl -fcnuse@*/
  492. /*@observer@*/ const char * poptGetInvocationName(poptContext con)
  493.     /*@*/;
  494. /*@=redecl =fcnuse@*/
  495.  
  496. /** \ingroup popt
  497.  * Shuffle argv pointers to remove stripped args, returns new argc.
  498.  * @param con        context
  499.  * @param argc        no. of args
  500.  * @param argv        arg vector
  501.  * @return        new argc
  502.  */
  503. /*@-fcnuse@*/
  504. int poptStrippedArgv(poptContext con, int argc, char ** argv)
  505.     /*@modifies *argv @*/;
  506. /*@=fcnuse@*/
  507.  
  508. /**
  509.  * Save a long, performing logical operation with value.
  510.  * @warning Alignment check may be too strict on certain platorms.
  511.  * @param arg        integer pointer, aligned on int boundary.
  512.  * @param argInfo    logical operation (see POPT_ARGFLAG_*)
  513.  * @param aLong        value to use
  514.  * @return        0 on success, POPT_ERROR_NULLARG/POPT_ERROR_BADOPERATION
  515.  */
  516. /*@-incondefs@*/
  517. int poptSaveLong(/*@null@*/ long * arg, int argInfo, long aLong)
  518.     /*@modifies *arg @*/
  519.     /*@requires maxSet(arg) >= 0 /\ maxRead(arg) == 0 @*/;
  520. /*@=incondefs@*/
  521.  
  522. /**
  523.  * Save an integer, performing logical operation with value.
  524.  * @warning Alignment check may be too strict on certain platorms.
  525.  * @param arg        integer pointer, aligned on int boundary.
  526.  * @param argInfo    logical operation (see POPT_ARGFLAG_*)
  527.  * @param aLong        value to use
  528.  * @return        0 on success, POPT_ERROR_NULLARG/POPT_ERROR_BADOPERATION
  529.  */
  530. /*@-incondefs@*/
  531. int poptSaveInt(/*@null@*/ int * arg, int argInfo, long aLong)
  532.     /*@modifies *arg @*/
  533.     /*@requires maxSet(arg) >= 0 /\ maxRead(arg) == 0 @*/;
  534. /*@=incondefs@*/
  535.  
  536. /*@=type@*/
  537. #ifdef  __cplusplus
  538. }
  539. #endif
  540.  
  541. #endif
  542.